/*
 * Copyright 2011 The Rusted Roof, LLC.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

package org.proteusframework.api.config;

import org.proteusframework.api.model.INamedObject;

import java.util.Collection;

/**
 * Dynamically configures an object using a well-defined, queryable set of configuration properties. Any property
 * can be marked as mandatory or optional.
 * <p/>
 * Configurable objects provide maximum flexibility without imposing an inordinate amount of method signatures across
 * an interface.
 *
 * @author Tacoma Four
 */
public interface IConfigurable extends INamedObject
{
    /**
     * Defines a runtime configuration property for the given key.
     *
     * @param prototype     Configuration property key
     * @param assignedValue Value to associate with the key
     * @throws IllegalArgumentException when the key does not match a well-defined configurable property
     */
    void setConfigProperty(IConfigPropertyPrototype prototype, Object assignedValue);

    /**
     * Locates the defined configuration property for the given key.
     *
     * @param key Configuration property key to lookup
     * @return Configuration property, or null if no configuration property has been set under that key
     */
    IConfigProperty getConfigProperty(String key);

    /**
     * Collection of all defined configuration properties. These are values actually set by a caller, and may not
     * represent the complete list of configuration property prototypes supported by the configurable object.
     *
     * @return Collection of defined configuration properties
     */
    Collection<IConfigProperty> configuredProperties();

    /**
     * Defines a runtime configuration property, as read from an XML configuration file. The assigned value is
     * guaranteed to be a non-null String. It is the responsibility of the configurable object to parse and process
     * the String into a meaningful object, as required.
     *
     * @param property Runtime property to define
     */
    void processRawProperty(IConfigProperty property);
}
